% CONFIGURAZIONE DEL DOCUMENTO
\documentclass[a4paper,11ptn]{report}
\usepackage[italian]{babel}
\usepackage{graphicx}
\usepackage[colorlinks=true]{hyperref}
\usepackage{url}
\usepackage{eurosym}
\usepackage{lastpage}
\usepackage{fancyhdr}
\hypersetup{linkbordercolor=1 1 1}
\hypersetup{urlcolor=blue}
\hypersetup{linkcolor=black}
\graphicspath{{../immagini/}}

% MACRO DEL DOCUMENTO
\newcommand{\Documento}{Norme di progetto}
\newcommand{\Sommario}{Norme interne per il progetto \textit{SIFISY} necessarie per regolamentare lo svolgersi delle attivit\`a di sviluppo.}
\newcommand{\CodiceRevisione}{RA}
\newcommand{\DataCreazione}{29 Novembre 2009}
\newcommand{\Versione}{3.1}
\newcommand{\StatoDocumento}{Formale, Interno}
\newcommand{\Redazione}{Giuseppe Biolo}
\newcommand{\Verifica}{Samuele Faggian}
\newcommand{\Approvazione}{Alessandro Vedovato}
\newcommand{\Committente}{Prof. Tullio Vardanega, Prof. Renato Conte}

% STILE GRAFICO PER LE PRIME PAGINE
\fancypagestyle{plain}{
\fancyhf{}
\fancyhead[L]{\Documento\ \Versione\ - \CodiceRevisione}
\fancyhead[R]{\includegraphics[scale=0.3]{logoSevenSoft.png}}
\fancyfoot[C]{\thepage}
}
\begin{document}
\pagenumbering{Roman}
\begin{center}
\includegraphics[scale=0.8]{logoSevenSoft.png} \\
\vspace*{1in}
\huge{\textbf{\textbf{\Documento}}} \\
\vspace*{2cm}
Versione: \Versione	\\
\vspace*{3cm}
\vspace*{0.5in}

% CONTENUTO DELLA PRIMA PAGINA
\textbf{Sommario} \\
\end{center}
\begin{normalsize}
\Sommario
\end{normalsize}

% SECONDA PAGINA CON LA DESCRIZIONE DEL CAPITOLATO
\newpage
\thispagestyle{plain}
\vspace*{0.5in}
\begin{center}
\begin{tabular}{l}
\Large{\textbf{Capitolato: Simulatore File System}} \\
\begin{tabular}{|p{5cm}|p{7cm}|}
\hline
\textbf{Data creazione:} & \DataCreazione \\
\hline
\textbf{Versione:} & \Versione \\
\hline
\textbf{Stato del documento:} & \StatoDocumento \\
\hline
\textbf{Redazione:} & \Redazione \\
\hline
\textbf{Revisione:} & \Verifica  \\
\hline
\textbf{Approvazione:}  & \Approvazione \\
\hline
\textbf{Committente:} & \Committente \\
\hline
\end{tabular} \\
\end{tabular}
\end{center}

% TERZA PAGINA CON IL DIARIO DELLE MODIFICHE
\newpage
\thispagestyle{plain}
\begin{center}
\begin{tabular} {l}
\Large{\textbf{Legenda Diario delle modifiche}} \\
\begin{tabular}{|p{3cm}|p{7cm}|}
\hline
Vers & Versione del documento \\
\hline
Verif & Verificatore del documento \\
\hline
Resp & Responsabile che approva il documento \\
\hline
GB & Giuseppe Biolo \\
\hline
DDM & Daniele De Matteo \\
\hline
SF & Samuele Faggian \\
\hline
AL & Alberto Longato \\
\hline
AV & Alessandro Vedovato \\
\hline
LZ & Luca Zanini \\
\hline
\end{tabular} \\
\end{tabular}
\end{center}

\vspace*{2cm}

\begin{center}
\begin{tabular}{l}
\Large{\textbf{Diario delle modifiche}} \\
\begin{tabular}{|p{0.7cm}|p{1.9cm}|p{1.2cm}|p{1cm}|p{1cm}|p{6.9cm}|}
\hline
\textbf{Vers} & \textbf{Data} & \textbf{Autore} & \textbf{Verif} & \textbf{Resp} & \textbf{Descrizione} \\
\hline
\hline
3.1 & 08/07/2010 & GB & ?? & ?? & Ampliamento della sezione sulle norme di progettazione \\
\hline
3.0 & 22/06/2010 & GB & AV & SF & Ultime correzioni per la consegna della revisione RQ \\
\hline
2.4 & 20/03/2010 & GB & SF & AV & Correzioni varie al contenuto del documento \\
\hline
2.3 & 02/02/2010 & GB & SF & AV & Completamento delle norme di codifica e delle norme di verifica del codice \\
\hline
2.2 & 22/01/2010 & DDM & SF & AV & Prima stesura delle norme di programmazione \\
\hline
2.1 & 20/01/2010 & DDM & SF & AV & Modificato il layout e aggiunto il sommario \\ 
\hline
2.0 & 14/01/2010 & SF & GB & LZ & Aggiunta la sezione delle norme di progettazione \\
\hline
1.0 & 09/12/2009 & GB & AV & DDM & Ultime correzioni per revisione RPP \\
\hline
0.6 & 08/12/2009 & GB & LZ & DDM & Modificato il layout con l'aggiunta del logo e correzioni \\ 
\hline
0.5 & 04/12/2009 & GB & LZ & DDM & Modificati alcuni dettagli del layout \\
\hline
0.4 & 01/12/2009 & GB & LZ & DDM & Modificati alcuni dettagli del layout \\
\hline
0.3 & 30/11/2009 & GB & AL & DDM & Correzione del nome del gruppo \\
\hline
0.2 & 30/11/2009 & GB & AL & DDM & Spostamento del Diario delle modifiche \\
\hline
0.1 & 29/11/2009 & GB & AL & DDM & Prima stesura del documento \\
\hline
\end{tabular} \\
\end{tabular}
\end{center}

% INDICE DEL DOCUMENTO
\newpage
\tableofcontents

% STILE GRAFICO DELLE PAGINE EFFETTIVE DEL DOCUMENTO
\newpage
\pagenumbering{arabic}
\fancypagestyle{plain}{
\fancyhf{}
\fancyhead[L]{\Documento\ \Versione\ - \CodiceRevisione}
\fancyfoot[C]{\thepage\ di \pageref{LastPage}}
\fancyhead[R]{\includegraphics[scale=0.3]{logoSevenSoft.png}}
}
\pagestyle{plain}

% INIZIO DEL DOCUMENTO

% Capitolo 1 - INTRODUZIONE AL DOCUMENTO
\chapter{Introduzione}

\section{Scopo del documento}
Questo documento definisce le norme di comportamento del gruppo nella stesura di documentazione interna ed esterna, nella comunicazione di gruppo e nella relazione con il cliente. Inoltre definisce tutte le \underline{best practices} che verranno adottate.\\
Ogni membro del team SevenSoft \`e tenuto leggere con attenzione il presente documento ed applicarne in modo pi\`u coerente possibile il contenuto, con il fine di ottimizzare il lavoro in team e le risorse a disposizione. Altro obbiettivo di questo documento \`e di facilitare la comprensione del codice e delle scelte compiute dal team.\\
Molte delle norme di codifica sono state scritte riferendosi alle convenzioni sul codice Java della Sun Microsystems.\\
Sar\`a compito del Responsabile verificare che tali norme vengano applicate. Tutti i componenti del gruppo possono eventualmente proporne delle nuove.

\section{Glossario}
Il glossario viene fornito in un documento separato denominato glossario-2.2.pdf che raccoglie le definizioni, acronimi ed abbreviazioni di tutta la documentazione.\\
In ogni documento i termini presenti nel glossario verranno marcati con una \underline{sottolineatura}.

\section{Riferimenti}
\begin{itemize}
\item Ian Sommerville, Software Engineering, Addison Wesley, 8a edizione (04 Giugno 2006).\\
ISBN: 978-0321313799
\item Assembla Home Page\\
    \url{http://www.assembla.com}
\item LaTeX - A document preparation system\\
    \url{http://www.latex-project.org}
\item BOUML Web Site\\
    \url{http://bouml.free.fr}
\item Subversion\\
    \url{http://subversion.tigris.org}
\item Gantt Project - Project Management as free as bee(r)\\
    \url{http://www.ganttproject.biz}
\item Java Programming Style Guidelines\\
    \url{http://geosoft.no/development/javastyle.html}
\item JUnit Unit Test Framework\\
    \url{http://www.junit.org}
\item GNU Aspell\\
    \url{http://aspell.net}
\item EMMA: a free Java code coverage tool\\
	\url{http://emma.sourceforge.net}
\end{itemize}

% Capitolo 2 - NORME DI COMPORTAMENTO
\chapter{Norme di comportamento}

\section{Comportamento generale}
Ad ogni componente del gruppo verr\`a richiesto di partecipare alla stesura dei documenti e del codice tramite l'apertura di ticket su \underline{Assembla}.\\
Il documento verr\`a  creato inserendo l'elenco dei capitoli, delle sezioni e delle sottosezioni all'interno di un modello comune in \LaTeX\ predisposto a tal fine.\\
Una volta creato il documento dovr\`a poi essere caricato nel repository \underline{SVN} esclusivamente in formato sorgente \LaTeX\ . Eventuali figure previste dai documenti dovranno essere in formato PNG e raggruppate nella directory dedicata \textit{immagini}.
Nel repository si troveranno anche altri documenti da supporto allo svolgimento del lavoro nel formato ritenuto pi\`u adatto al loro uso.\\
Dovr\`a inoltre essere sempre aggiornato uno script pdf.sh che contiene uno script sh per la compilazione 
di tutti i file \LaTeX\ presenti nella directory.

\section{Uso della e-mail del gruppo}
Le comunicazioni verso l'esterno del team, principalmente con il committente, avvengono tramite l'e-mail sevensoftse@gmail.com.\\
La gestione della corrispondenza \`e a carico del Responsabile, che cura sia la posta in ingresso che quella in uscita.\\
Nel caso di e-mail in ingresso il Responsabile avr\`a il compito di inoltrarle a tutti gli altri componenti, mentre nel caso di invio di e-mail all'esterno il Responsabile dovr\`a preventivamente consultare tutti i componenti del gruppo sul contenuto, in particolare i componenti del team che potrebbero avere competenze sull'argomento in questione o dipendenze da esso.

\section{Uso dello spazio web di Assembla}
Lo spazio web di Assembla raggiungibile all'URL \url{https://www.assembla.com/flows/flow/adg2l2s} viene utilizzato come repository comune per il sorgente del progetto.\\
L'accesso al versionamento dei sorgenti avviene solo previa registrazione, mentre l'accesso alla consultazione del sorgente \`e aperto a tutti essendo il progetto open-source (protetto da licenza GPL) ed avviene accedendo all'URL \url{http://svn2.assembla.com/svn/adg2l2s}.

\section{Condivisione, archiviazione e versionamento dei file}
Per garantire la consistenza di ogni documento e file condiviso, a fronte di cambiamenti (potenzialmente simultanei) da parte dei componenti del gruppo, verr\`a utilizzato un server \underline{Subversion} in abbinamento con un client \underline{SVN}, nello specifico Subversion.\\
Ad ogni componente del gruppo sono state spiegate le dinamiche del versionamento e l'uso di tale strumento.\\
Questo strumento permette di garantire l'atomicit\`a di ogni aggiornamento inviato al repository ed in caso di errori in aggiornamento permette di tornare a versioni precedenti l'errato inserimento.\\
Il server \underline{Subversion} utilizzato dal gruppo \`e messo a disposizione da \underline{Assembla} all'indirizzo \url{http://code.assembla.com/adg2l2s/subversion/nodes}.

\subsection{Utilizzo server SVN}
Ad ogni modifica del contenuto del repository \`e necessario eseguire un \underline{commit} dei dati modificati nel server Subversion. Contestualmente al commit si richiede di aggiungere opportuni commenti, in particolare bisogna fornire descrizione delle modifiche fatte. Se le modifiche fatte riguardano un compito assegnato tramite ticket \`e sufficiente indicare il numero del ticket relativo e discutere nel ticket di \underline{Assembla} le modifiche.\\
Un esempio di massima di un buon commento:\\
''eseguite varie modifiche a normeDiProgetto-1.0.tex, lista delle modifiche al commento 3 del ticket 13.''\\
Si sconsigliano commenti in cui:
\begin{itemize}
    \item Ci si riferisce ad un documento con il nome di una persona, es: ''Documento di Cesare.''
    \item Ci si riferisce ad un documento con il nome senza indicare il formato ed il filename esatto, es: ''modificato il file in cui si specificano le norme''
    \item Si danno indicazioni temporali inutili, es: ''Ultima modifica di ieri.''
    \item Si danno valutazioni superflue, es: ''File ultra corretto, fatto stamattina prestissimo.''
\end{itemize}

\subsection{Versionamento dei file}
Per identificare la versione di un documento alla fine del nome dovr\`a essere aggiunto il codice identificativo. Un esempio di nome di file valido:\\
''normeDiProgetto-1.0.pdf''.\\
Nell'identificativo di versione la prima cifra da sinistra verr\`a incrementata solo dopo una revisione (ovvero, conclusa la prima revisione si inizier\`a con la versione 2.0), la seconda cifra invece verr\`a cambiata a discrezione del redattore del documento.

\subsection{Convocazioni ed incontri}
Ogni incontro, sia interno che esterno, dovr\`a essere preceduto da un annuncio in bacheca e dall'approvazione del Responsabile. Al termine di qualsiasi incontro dovr\`a essere redatto un resoconto che contenga sinteticamente i risultati o i problemi emersi durante la discussione.

\subsubsection{Interni}
La cadenza degli incontri interni \`e fissata dal Responsabile e comunicata ai membri del team tramite segnalazione in bacheca. Automaticamente sar\`a inviata via e-mail una notifica della convocazione a tutti i membri del gruppo.\\
Il Responsabile si occuper\`a di volta in volta di selezionare l'ordine del giorno appropriato e di controllare il corretto svolgimento dell'incontro. Gli argomenti da discutere e da inserire nell'ordine del giorno potranno essere proposti da qualsiasi membro del gruppo e saranno inseriti nell'annuncio di convocazione in bacheca, previa approvazione del Responsabile.

\subsubsection{Esterni}
Ogni membro del gruppo ha facolt\`a di chiedere al Responsabile un incontro con il Committente. Spetta al Responsabile valutare la richiesta e, se lo ritiene opportuno e utile al progetto, approvare l'incontro.\\
Per formalizzare l'incontro dovr\`a essere pubblicato in bacheca il messaggio di convocazione, la cui notifica arriver\`a a tutti i membri del team.\\
All'incontro \`e obbligatoria solamente la presenza del richiedente, ma non si esclude la presenza di qualsiasi altro membro del gruppo che reputi di interesse tale incontro con il Committente.

% Capitolo 3 - CONVENZIONI TIPOGRAFICHE
\chapter{Convenzioni tipografiche}

\section{Convenzioni per i documenti}
I documenti redatti, oltre che seguire il modello messo a disposizione, dovranno anche rispettare le seguenti convenzioni tipografiche:
\begin{itemize}
    \item Gli indirizzi Internet dovranno essere scritti utilizzando il comando \LaTeX\ \begin{verbatim} \url{indirizzo} \end{verbatim}
    \item I termini definiti nel glossario verranno contrassegnati da una sottolineatura con il comando \LaTeX\ \begin{verbatim} \underline{termine} \end{verbatim}
    \item Punto, virgola, punto e virgola, due punti, punto esclamativo e punto interrogativo sono attaccate alla parola che li precede, mentre sono separate con uno spazio dalla parola che li segue;
    \item Gli accenti in italiano sono sempre gravi, tranne nelle parole accentate che finiscono in -ch\`e, in -n\`e e in -s\`e;
    \item Gli acronimi e sigle, per distinguerli come tali dal resto del testo, verranno scritti in maiuscolo. Nella documentazione verranno spesso utilizzati acronimi del tipo URL, \underline{SVN}, SVG, \underline{BOUML}, etc.;
    \item Non verranno usati acronimi in maiuscolo quando questi rappresentano marchi registrati (es. Sun Microsystems), oppure necessitano di essere scritti minuscoli per motivi specifici (es. svn quando ci si riferisce al client Subversion invocabile da shell);
    \item Sono permessi spazi singoli o doppi tra linee di testo a discrezione dell'autore;
    \item I nomi di qualifica di ruolo all'interno della SevenSoft vanno scritti con iniziale maiuscola (es. Amministratore, Responsabile, Verificatore);
    \item I riferimenti bibliografici a pubblicazioni vengono redatti secondo lo standard ISO 690-2:1997 ''Information and documentation - bibliographic references - part 2 : electronic documents or parts thereof'', quindi brevemente verranno indicati in questo ordine:
        \subitem Autore
        \subitem Titolo
        \subitem Citt 
        \subitem Editore
        \subitem Anno
        \subitem ISBN \\
Come ISBN si preferiscono nell'ordine: ISBN13, Bookland EAN, ISBN10 ed infine, ove non si trovi uno dei precedenti, un qualsiasi URN reperibile.
\end{itemize}

\subsection{Convenzioni per i nomi dei file}
I nomi di tutti i file sia di sorgente che di documentazione dovranno avere un nome significativo rispetto al loro contenuto.\\
Inoltre:
\begin{itemize}
    \item Potranno essere usati solo caratteri dell'alfabeto inglese dalla ''a'' alla ''z'' e ''-'' solo dove specificato;
    \item Non dovranno essere utilizzati caratteri speciali;
    \item Non dovranno essere utilizzati caratteri accentati;
    \item I nomi utilizzati non dovranno contenere spazi;
    \item {Se il nome da utilizzare \`e composto da pi\`u parole, queste dovranno essere unite e messe in maiuscolo dalla seconda parola in poi come da esempio sotto:\\
''normeDiProgetto''\\
Se il nome del file contiene gi\`a caratteri speciali, questi vengono eliminati o sostituiti con un carattere non speciale;\\}
\end{itemize}

\subsection{Convenzioni Tipografiche \LaTeX}
Tutti i documenti prodotti da SevenSoft vengono redatti in \LaTeX\ con estensione *.tex e seguono il modello unico definito come standard di gruppo.\\
I sorgenti \LaTeX\ della documentazione devono poter essere compilati automaticamente dallo script pdf.sh che deve essere mantenuto aggiornato per invocare correttamente il comando pdflatex per tre volte su ogni singolo sorgente.\\
Segue una lista di norme:\\
\begin{itemize}
    \item Gli URL quando si vuole che appaia il link per esteso ed evidenziato in blu devono essere racchiusi dal tag:
        \begin{verbatim}
            \url{http://bouml.free.fr/doc/plugout.html}
        \end{verbatim}
quando si vuole aggiungere un link che venga per\`o mostrato come una normale parola nel testo, senza che appaia l'intero URL, si utilizzer\`a  invece:
        \begin{verbatim}
            \htmladdnormallink{GNU Aspell}{http://aspell.net/}
        \end{verbatim}
    \item Sono ammessi due tipi di lista e bisogna discriminare bene su quale delle due sia pi\`u indicata, quella numerata o quella con bullet:
	    \begin{verbatim}
	    	\begin{itemize}
	    	  \item Gallia est omnis divisa in partes tres 
	    	\end{itemize}
	    \end{verbatim}
	    \begin{verbatim}
	    	\begin{enumerate}
	    	  \item Provinciae toti quam maximum potest militum numerum imperat
	    	\end{enumerate}
	    \end{verbatim}
    \item Per inserire riferimenti ad altri capitoli o sottosezioni si usano rispettivamente la coppia di comandi:
    \begin{verbatim}
        \ref{chapter:nomeReference}
        \label{chapter:nomeReference}
    \end{verbatim}
    \begin{verbatim}
        \ref{sub:nomeReference}
         \label{sub:nomeReference}
	\end{verbatim}
	Per le modalit\`a d'uso dei due comandi si consulti un manuale \LaTeX\ .
\end{itemize}

%Capitolo 5 - NORME DI VERIFICA DEI DOCUMENTI
\chapter{Norme di verifica dei documenti}
La fase operativa di verifica inizia dopo la stesura preliminare del documento, quest'ultimo deve avere una struttura gi\`a definita ed un contenuto sufficiente per effettuare la verifica.\\
I Verificatori hanno i seguenti compiti:
\begin{itemize}
	\item Controllare il documento dal punto di vista sintattico;
	\item Controllare la semantica, in modo da eliminare qualsiasi ambiguit\`a;
	\item Controllare la correttezza del contenuto del documento rispetto alla natura del documento stesso;
\end{itemize}
Nel caso vengano individuati errori di piccola entit\`a, ovvero riguardanti la punteggiatura o l'ortografia, il Verificatore pu\`o porvi rimedio senza interpellare l'autore del documento.\\
Nel caso invece vengano rilevati degli errori di una maggiore entit\`a, ad esempio per scarsa chiarezza del contenuto o contenuto non idoneo, il Verificatore non potr\`a assolutamente effettuare modifiche, ma dovr\`a invece segnalarle a colui che ha redatto il documento, che avr\`a la responsabilit\`a di porvi rimedio.\\
In ogni caso, dopo qualsiasi modifica del contenuto, il documento dovr\`a essere sottoposto nuovamente a verifica.

\section{Uso di Aspell}
Per la correzione automatizzata della documentazione verr\`a utilizzata l'applicazione \underline{Aspell}, che permette di semplificare il processo di verifica eliminando il problema dell'individuazione gli errori ortografici mediante semplice lettura.

% Capitolo 6 - PRESENTAZIONI
\chapter{Convenzioni sulle presentazioni}
Le presentazioni relative ad ogni revisione a cui il team SevenSoft parteciper\`a dovranno essere create usando il relativo template \LaTeX\ disponibile nel repository del team.\\
Dovranno poi essere esportate in pdf per la presentazione.\\
La scrittura dei contenuti dovr\`a seguire le norme tipografiche usate per la creazione della documentazione. Particolare attenzione dovr\`a essere posta nel limitare la quantit\`a di testo presente in ogni slide. Dovr\`a essere data priorit\`a alla presenza di concetti e parole chiave.\\
\`E consigliato l'uso di figure ed illustrazioni che aiutino a rendere agevole la comprensione dei concetti discussi.\\
Non \`e fissato a priori un numero massimo di slide per ogni presentazione.

%Capitolo 4 - NORME DI PROGETTAZIONE
\chapter{Norme di Progettazione}
Nel corso dello sviluppo del progetto si render\`a necessario far uso di diagrammi di vario tipo. Tutti i diagrammi che verranno realizzati dovranno rispettare le specifiche UML 2.1.\\
Per tali rappresentazioni sar\`a utilizzato il software \underline{BOUML}, alla versione 4.17.x, disponibile sotto licenza GNU \underline{GPL}, per cui liberamente utilizzabile.
\section{Utilizzo di BOUML}
Ogni progettista sar\`a tenuto a rispettare le seguenti regole:
\begin{enumerate}
	\item Per un'adeguata suddivisione del progetto a livello di gruppo ad ogni progettista sar\`a assegnato uno o pi\`u ''Package'' che permetteranno di lavorare in maniera distribuita;
	\item La divisione dei package sar\`a a carico dell'Amministratore di turno. A tale scopo quest'ultimo dovr\`a fare uso esplicito del programma ''Project Control''. Nessun'altro potr\`a modificare o riassegnare pacchetti in modo casuale. Questo permette che pacchetti assegnati ad un certo progettista siano visualizzati in modalit\`a READ ONLY ad altri progettisti;
	\item I nomi assegnati alle modalit\`a (View) che possono essere creati all'interno di \underline{BOUML}, dovranno essere accompagnati da una sigla identificativa:
		\begin{itemize}
			\item Use case View: UV
			\item Class View: CV
			\item Component View: CoV
			\item Deployment View: DV
		\end{itemize}
		Lo stesso vale per i diagrammi:
		\begin{itemize}
			\item Use case diagram: UD
			\item Class diagram: CD
			\item Sequence diagram: SD
			\item Communication diagram: CoD
			\item Object diagram: OD
		\end{itemize}
	\item Il salvataggio dei progetti \underline{BOUML} dovr\`a essere effettuato nell'apposita cartella presente nel \underline{repository} denominata ''Bouml'', e il nome del progetto dovr\`a indicare chiaramente la componente a cui si riferisce il diagramma, ovvero ''GUI'', ''Model'' o ''Controller'';
	\item Nei diagrammi UML devranno essere indicati solo i metodi effettivi delle classi, mentre i metodi get e set, a meno di particolari casi in cui il metodo non ritorni il solo valore del relativo attributo, dovranno essere omessi;
	\item Tutti i diagrammi realizzati, se ritenuti corretti, dovranno essere esportati in formato PNG, sfruttando la funzionalit\`a apposita fornita dallo stesso \underline{BOUML}, per renderli inseribili nella documentazione;
	\item L'utilizzo della colorazione nei diagrammi \underline{UML} dovr\`a seguire l'impostazione di default di \underline{BOUML}, ovvero con lo sfondo del diagramma bianco, l'interno delle classi in giallo e le rimanenti componenti in nero. Eventuali eccezioni sono concesse solo nel caso di diagrammi puramente dimostrativi, senza valore a livello tecnico;
	\item Anche se \underline{BOUML} prevede la funzionalit\`a di generazione automatica del codice, questa non sar\`a utilizzata in favore dell'utilizzo del generatore automatico di codice integrato nell'\underline{IDE} \underline{NetBeans}.\\
\end{enumerate}

% Capitolo 7 - NORME DI CODIFICA
\chapter{Norme di Codifica}
Per la stesura del codice (incluso quello per i test di verifica) \`e stato ritenuto opportuno utilizzare un 
sottoinsieme delle norme gi\`a esistenti sotto il nome di Java Code Conventions.\\
Inoltre SevenSoft ha deciso che i nomi di tutte le classi, metodi e variabili saranno in lingua inglese.\\
Di seguito sono elencate le norme di codifica che verranno adottate:

\section{File sorgente}
Dovr\`a contenere al pi\`u una singola classe pubblica o interfaccia. La classe pubblica deve essere la prima classe o interfaccia del file. Segue una descrizione dell'ordine in cui viene redatto un file sorgente:
\begin{enumerate}
	\item Tutti i file sorgenti dovranno iniziare con il commento relativo alla \underline{licenza GPL};
	\item La prima riga dopo il commento conterr\`a, se necessario, una dichiarazione e solo in seguito un' importazione di package;
	\item Le classi o interfacce all'interno del file dovranno contenere in ordine:
	\begin{enumerate}
		\item Commento di documentazione della classe;
		\item Dichiarazione della classe;
		\item (opzionale) Commento di implementazione;  
		\item Variabili statiche nell'ordine: pubbliche, protette ed infine private;
		\item Variabili d'istanza nello stesso ordine delle variabili statiche;
		\item Costruttori;
		\item Dichiarazione di metodi possibilmente ordinati per funzionalit\`a piuttosto che per livello di accessibilit\`a;
	\end{enumerate}
\end{enumerate}
 
\section{Complessit\`a ciclomatica}
La \underline{complessit\`a ciclomatica} \`e una particolare metrica sulla complessit\`a del codice.\\
Le metriche sul software hanno la caratteristica generale di essere indici inconfutabili ed oggettivi, e di essere al contempo soggettivi nel momento in cui vengono applicati ad un particolare dominio.\\
L'indice di complessit\`a ciclomatica, ad esempio, non \`e un indice assoluto di qualit\`a del codice, come potrebbe non esserlo un basso accoppiamento del codice (si potrebbe aver scelto di scrivere codice altamente accoppiato per motivi prestazionali).\\
SevenSoft nel caso specifico di questo progetto ha per\`o riconosciuto la complessit\`a ciclomatica come un buon indice di bassa complessit\`a nell'interpretazione del codice da parte dei suoi futuri manutentori.\\
Si \`e pertanto deciso di limitarla ad un indice massimo di 5 che risulta essere per altro un indice generalmente basso.

\section{Indentazione}
Vanno usati 4 spazi come unit\`a di indentazione.

\section{Lunghezza di una linea}
Su una singola riga possono essere scritti al pi\`u 80 caratteri.

\section{Interruzione delle linee}
Quando un'espressione \`e troppo lunga per stare su un'unica riga, deve venire spezzata secondo le seguenti regole:
\begin{itemize}
	\item Dopo una virgola;
	\item Prima di un operatore;
	\item La parte di espressione rimanente va indentata con 8 spazi rispetto all'inizio della prima parte di espressione;
\end{itemize}

\section{Commenti}
I commenti devono essere utilizzati per dare una descrizione del codice fornendo informazioni aggiuntive
che non sono facilmente intuibili a partire dal codice stesso. A volte per\`o l'utilizzo eccessivo di 
commenti riflette una scarsa qualit\`a del codice, sar\`a perci\`o compito del Programmatore evitarlo, preferendo una scrittura pi\`u chiara.\\
La documentazione del codice sar\`a generata in automatico, mediante il tool \underline{Javadoc}, partendo dai commenti interni al codice. Quindi la struttura dei commenti dovr\`a anche rispettare le regole imposte da \underline{JavaDoc}.
 
\subsection{Commenti di implementazione}
Commentano il codice in base ad una particolare implementazione. Sono delimitati da /*...*/ e si 
suddividono in quattro categorie:
\begin{itemize}
	\item Commenti a blocco: Vengono usati per descrivere file, metodi, strutture dati e algoritmi. Vengono usati all'inizio di ogni file, prima o all'interno di un metodo. Devono essere preceduti da una linea vuota e contengono un asterisco all'inizio di ogni riga eccetto la prima;\\\\
/*\\
{*Questo è un block comment}\\ 
{*/}\\
	\item Commenti a linea singola: Devono essere indentati al livello del codice che li segue. Devono essere preceduti da una linea vuota e nel caso in cui superino la lunghezza di una linea devono seguire le norme adottate per i Commenti a blocchi;\\\\ 
 \ \ \ /* Handle the condition*/\\ 
 \ \ \ ...\\ 
	\item Commenti a fine linea: Vengono definiti tramite il delimitatore di commenti ``//'', non dovr\`a venir usato per scrivere commenti su pi\`u linee ma potr\`a essere adoperato per togliere una parte di codice commentandolo.\\\\
{\color{white}//}...\\
//if(bar==1){\{}\\
//\\ 
// \ \ //Do a triple flip\\ 
// \ \ ...
\end{itemize}
 
\subsection{Commenti di documentazione}
Descrivono la specifica del codice astraendolo dall'implementazione, sono delimitati da /**...*/ e possono venir letti e capiti anche senza vedere il codice. Descrivono classi, interfacce, costruttori, metodi e campi. Sar\`a possibile inserire un solo commento per ogni classe, interfaccia o membro.\\
La prima linea del commento di documentazione non \`e indentata mentre le successive vanno indentate di uno spazio per ordinare verticalmente gli asterischi. Non possono venir posizionati all'interno del corpo di metodi o costruttori. Deve apparire subito prima di una dichiarazione:\\\\
/** \\
{\color{white}/}* commento di documentazione\\
{\color{white}/}*/\\
public class Esempio{\{}...{\}}

\section{Dichiarazioni}
Ci dovr\`a essere una sola dichiarazione per linea ed in nessun caso ci dovranno essere tipi differenti 
o combinazioni di variabili e metodi dichiarati sulla stessa linea. Le variabili verranno dichiarate
 all'inizio dei blocchi e non nel momento dell'uso, ad eccezione dell'indice per il ciclo ``for''. Da evitare dichiarazioni locali che nascondono dichiarazioni di livello pi\`u alto.  

\section{Dichiarazioni di Classi ed Interfacce}
\begin{itemize}
	\item Non ci dovranno essere spazi tra il nome dei metodi e le parentesi contenenti i parametri;
	\item La parentesi graffa va aperta alla fine della stessa riga in cui c'\`e stata la dichiarazione dello statement;
	\item La parentesi graffa va chiusa in una nuova linea ordinandola verticalmente con la parentesi aperta corrispondente con l'eccezione del corpo vuoto quando appare immediatamente dopo quella aperta;
	\item I metodi sono separati da una linea vuota;
\end{itemize}

\section{Convenzioni di denominazione}
\begin{itemize}
	\item Classi: la prima lettera del nome della classe deve essere scritta in maiuscolo, nei nomi composti da pi\`u parole la prima lettera di ogni parola deve essere scritta in maiuscolo. Il nome deve essere 
semplice e descrittivo, da evitare acronimi e abbreviazioni. Esempi: class Raster; class ImageSprite;
	\item Interfacce: valgono le stesse regole delle classi;
	\item Metodi: devono essere verbi, la prima lettera deve essere minuscola mentre, se il nome \`e composto da pi\`u parole, la prima lettera delle parole interne deve essere maiuscola. Esempi: run(); runFast();
	\item Variabili: devono essere corte ma con un significato tale da far percepire ad un osservatore casuale lo scopo della variabile;
	\item Costanti: tutte le lettere delle costanti devono esser scritte in maiuscolo con le parole separate da (``\_'');
\end{itemize}

\subsection{Documentazione}
La documentazione del codice sar\`a fatta in \underline{Javadoc}. Come conseguenza di tale scelta le regole per la stesura della documentazione saranno quelle stabilite per \underline{Javadoc}.

\subsection{File XML}
Per la stesura del codice XML, sia che si tratti di file di configurazione che di simulazioni e progetti, si seguiranno delle regole comuni.
\begin{itemize}
	\item Tag: I tag XML dovranno rispecchiare i nomi delle entit\`a che descrivono. Ad esempio se il tag descrive un esempio, esso si chiamer\`a \texttt{<esempio>};
	\item Indentazione:	Vanno usati quattro spazi come unit\`a di indentazione;
	\item Commenti: I commenti dovranno essere il minor numero possibile, se necessari essi dovranno essere inseriti sopra ci\`o che si vuole commentare;
\end{itemize}

% Capitolo 8 - NORME DI VERIFICA DEL CODICE
\chapter{Norme di verifica del codice}

\section{Uso di JUnit}
Per le verifiche di unit\`a (unit testing) verr\`a utilizzato il \underline{framework} \underline{JUnit} che permette di scrivere facilmente test ripetibili grazie a dei metodi che permettono di verificare se un'unit\`a sotto test si comporta come ci si aspettava.\\
Questi metodi infatti permettono di eseguire chiamate ai metodi dell'unit\`a sotto test, e si occupano poi di controllare che il valore ritornato da questi sia corretto (in relazione all'input fornito).

\subsection{Esecuzione dei test di unit\`a JUnit}
Per l'esecuzione dei test JUnit si utilizzar\`a l'IDE NetBeans, che permette di gestire i test in relazione al progetto a cui si st\`a lavorando.

\subsection{Regole di applicazione}

\subsubsection{Classi da testare}
Verranno sottoposti a verifica solo i componenti di modello e persistenza, diversamente tale tipo di test \`e stato ritenuto non produttivo per quanto riguarda interfacce e classi di controllo.

\subsubsection{Metodi da testare}
Verranno sottoposti a test solo i metodi che possono contenere errori, e cio\`e quelli che hanno una qualche logica applicativa. Ad esempio \`e ritenuto inutile il test dei metodi get e set delle classi sottoposte a test.

\subsubsection{Piano di test}
Per ogni metodo da verificare \`e necessario preparare un piano di test che copre le varie condizioni di utilizzo (condizioni particolari).\\
In generale saranno testate varie condizioni ordinarie (valori in ingresso nella norma) e varie condizioni scorrette (valori in ingresso non validi).

\subsubsection{Stile dei test}
I test sono codice aggiuntivo, quindi potenzialmente soggetto a sua volta ad errori. \`E opportuno che i metodi di test siano semplici e brevi per aiutare ad identificare le cause di errore.\\
Idealmente sarebbe indicato avere un unico metodo di test per ogni metodo da testare.

\subsubsection{Fallimento di un test}
Se viene individuato un baco durante l'esecuzione di un test, questo fornisce una immediata indicazione del
 componente e del metodo errati.\\
Tale stato erroneo dovr\`a essere riportato al responsabile di quel componente, nella fattispecie chi l'ha creato, che avr\`a il compito di correggere il problema.

\subsubsection{Individuazione di un errore}
Nel caso venga individuato un errore nel codice, non identificato dai test di unit\`a, se possibile, prima di correggere l'errore, \`e opportuno introdurre un nuovo test che ''catturi'' l'errore (test che fallisce a causa dell'errore).\\
Successivamente il reponsabile del componente, nella fattispecie chi l'ha creato, nel quale si trova l'errore lo dovr\`a correggere, e dovr\`a adattare la classe di test del componente ed eventualmente aggiungere una o pi\`u classi di test nel caso l'errore sia stato corretto introducendo una o pi\`u nuove componenti.

% Capitolo 9 - STRUMENTI
\chapter{Strumenti}
Per facilitare il lavoro di tutti i membri del team SevenSoft e per rendere interoperabili i loro risultati saranno ora elencati gli strumenti da usare per svolgere i vari compiti assegnati.\\
Salvo diverse indicazioni \`e fatto obbligo lo sviluppo di tutto il progetto con i medesimi software e lo stesso sistema operativo, per evitare problemi di incompatibilit\`a.\\
Per ogni membro del team tutti i software dovranno essere aggiornati alla versione riportata. Non \`e consigliato effettuare alcun aggiornamento dei software in corso d'opera.\\
Eccezione a quanto appena detto durante la fase di collaudo del sistema SiFiSy per testarne la portabilit\`a nei vari ambienti.\\
\begin{itemize}
    \item Tutto il progetto dovr\`a necessariamente essere sviluppato all'interno di un sistema operativo GNU/Linux. La scelta della distribuzione \`e ricaduta, per motivi di compatibilit\`a, diffusione e disponibilit\`a di documentazione, su Ubuntu 9.10 i386;
    \item Per la scrittura e la compilazione di tutta la documentazione e delle presentazioni verr\`a usato il programma Texmaker alla versione 1.9.2 in abbinamento al compilatore \LaTeX\ pdflatex compreso nella suite TexLive alla versione 2009.11;
    \item Per la stesura del diagramma di Gantt verr\`a utilizzato il programma GanttProject alla versione 2.0.10;
    \item Per la realizzazione dei diagrammi UML (USE-CASE, di classi, ecc.) verr\`a utilizzato il programma \underline{BOUML} alla versione 4.12.1;
    \item Per la scrittura e la compilazione del codice Java verr\`a utilizzato il programma NetBeans IDE alla versione 6.8 abbinato alla JDK 6 update 18;
    \item Per la realizzazione dei test di unit\`a verr\`a utilizzato il \underline{framework} \underline{JUnit} alla versione 4.8.1;
    \item Per la correzione automatizzata della documentazione verr\`a utilizzato l'applicativo GNU Aspell alla versione 0.60.6;
\end{itemize}

% FINE DEL DOCUMENTO
\end{document}
